README.TXT for MicroThread V2.5 What is MicroThread? MicroThread is a minimal Turbo C multi-threading library for DOS programs. Normal DOS programs are normally single-threaded, i.e. a single determinate path of execution. However, in certain situations, programs can be much easier to design if there can have multiple concurrent paths of execution, i.e. multi-threaded. MicroThread allows your Borland C DOS programs to have this multi-threading capability, simply and easily. MicroThread consists of a pre-emptive scheduling kernel which dispatch threads on every timer interrupt(INT 8). It has a priority- based scheduling algorithm, and has support for semaphores, critical sections and inter-thread messages. The main features of MicroThread are: 1) It is written entirely in Turbo C, with no assembly code, so that it can be easily understood and modified to suit your needs. 2) It is small. Unlike a number of other such libraries, MicroThread contains only the basic essential code to implement a multi-threading kernel for DOS programs and very little else. (Unfortunately the code has grown a bit with each version, but I will try to keep this down to a minimum). 3) It is FREE. I have placed the source code in the public domain in the hope that somebody else would find it useful. What MicroThread isn't: 1) MicroThread isn't a replacement for a "industrial-strength" multi- tasking or multi-threading kernel. It was written primarily as an aid for teaching multi-threading on an operating-systems course at the University of Wolverhampton, UK. 2) It is not in any way optimised, either in its algorithms, functionality, or speed. The code source was written in such a way that it would be easier to go through on an overhead projection screen in front of a class, rather than for elegance, style or speed. Thus, the verbosity of the code and comments may be a bit of an over- kill at times. What do you need? Though MicroThread was written mainly with Borland C V3.1, the source files should compile quite happy under most versions of Turbo/Borland C/C++. They have been compiled with the following versions: Turbo C V2.0, Turbo C++ V1.1, Borland C V3.1 and Borland C++ V4.5. The main MicroThread kernel is contained within the file MTHREAD.C and you will also need the header file MTHREAD.H. The file MTCRTLIB.C contains some C runtime library functions. Unfortunately Turbo C's runtime library functions were never designed for multi-threaded use, and are not re-entrant. Thus, you can't use them in a multi-threaded program, except if you guard against re-entering them from different threads at the same time. MTCRTLIB.C contains several functions which uses a semaphore to guard against re-entrancy problems in calls to Turbo C runtime function. The range of functions in MTCRTLIB.C are by no means complete, as they were the only ones I had need to date, but it should be straight forward enough add your own functions. It however, you have no need for the runtime library functions or are using runtime library functions in only one thread at any time, then you won't need MTCRTLIB.C Several example programs (DEMO1.C, DEMO2.C,...) are included within the distribution along with their project files(DEMO1.PRJ,etc.). The problem with project files is that they are version and installation specific. These particular ones are specific to my version(V3.1) and installation (C:\BORLANDC), so you may have to adjust the various options once you have loaded them. When you are building an application with MicroThread, there are several points to bear in mind: 1) MicroThread has only ever been tested with the large model. I haven't tried it with any other models yet as I very rarely use them (I haven't installed them to save on disk space) 2) MicroThread needs a stack frame. It uses different stacks to keep track of different threads. Thus you must build your application with the "Standard Stack Frame" option enabled. You mustn't however enable the stack overflow testing option. This will kill MicroThread stone- cold dead. 3) DOS is not re-entrant. So if you use any DOS functions or any C runtime functions which eventually calls DOS routines, MicroThread will stop multi-threading temporarily until the DOS routine returns. It accomplishes this by testing the InDOS flag. The upshot of this is that if you use Control-S or the PAUSE key to pause the screen output, you will effectively pause all threads in your program. 4) MicroThread will NOT run inside the Turbo C IDE debugger. The Turbo C IDE debugger get confused by MicroThread's stack switching and will crash. One possible way to trace through a MicroThread program is to use Turbo Debugger and trace through it at the instruction level(assembly code trace). Breakpoints, and stepping(rather than tracing) also don't work terribly well. 5) Floating point isn't supported at the moment. Turbo C's floating point emulator library isn't re-entrant, but can be guarded in the same way as the other runtime libraries. However, if you have a coprocessor or 486DX, then I am afraid things are not so great. Adding support for coprocessors will mean delving into assembly code, which confuses the issue would make MicroThread less of a useful teaching tool for me. One possible work-around is to limit floating point operations to only one thread, but this won't always work if the other thread are also using other C runtime functions. Oh well, such is life. More details Details of how to use MicroThread are contained with the file MTHREAD.TXT. The file describes the various functions and macros that your application can call to use MicroThread. Disclaimer Please do not hold me responsible if any of your programs break when you use MicroThread. The only thing I will guarantee is that MicroThread's behaviour is totally unpredictable, and will definitely crash, at some point. When it does crash, it will probably also take out whatever multi-tasking environment you happen to be running at the time, be it DR Concurrent DOS, Windows 3.1, Windows 95, OS/2 Warp, Windows NT, or Desqview. You have been warn Use and Distribution Please feel free to use and distribute the source code in any manner that you feel fit. If you do distribute your MicroThreaded applications, I would appreciate a mention. If you develop any extensions or modifications to MicroThread or demonstration programs that you want to distribute, I would be grateful if you drop me a note, so that I can mention it in this 'readme' file. Comments and suggestions would be very welcome to : Internet Email : i.h.ting@wlv.ac.uk Compuserve : 100023,3363 Otherwise : I H Ting University of Wolverhampton School of Computing & I. T. Wulfruna Street WOLVERHAMPTON WV1 1SB UK.